Skip to content

feat(cli): Add 'adk samples' command for easy sample discovery and setup #1077

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

lavinigam-gcp
Copy link

This commit introduces the new adk samples command-line interface, enabling users to easily discover, download, and prepare ADK example agents for local use.

Key features in this initial version:

  • Interactive Mode (adk samples):

    • Downloads official ADK samples from the GitHub repository to a local cache (default: ~/.adk/cache/samples/, customizable with --cache-path).
    • Displays a table of available samples, including their names and extracted descriptions from their agent.py files.
    • Prompts the user to choose a sample by number.
  • Direct Mode (adk samples <sample_name>):

    • Allows specifying a sample name directly for preparation.
    • Downloads samples to cache if not already present.
  • Sample Preparation:

    • Copies the selected sample from the local cache to an adk-samples subdirectory in the user's target output path (default: current working directory, customizable with --output-path).
    • Prompts the user for their Gemini API key (securely).
    • Creates a .env file within the prepared sample's directory, pre-filled with the GOOGLE_API_KEY and configured for Google AI Studio backend.
    • Provides clear "Next steps" guidance on how to run the prepared sample using adk web, adk run, or adk api_server.
  • Configuration:

    • Supports multiple sample sources via a configurable list (though V1 defaults to the official adk-python repository).
    • Allows user-defined cache path (--cache-path) and output base path (--output-path).

File Changes:

  • src/google/adk/cli/cli_samples.py: New file containing the core logic for downloading, caching, listing, copying samples, and .env creation.
  • src/google/adk/cli/cli_tools_click.py: Modified to register the new adk samples command and its options (--cache-path, --output-path).
  • pyproject.toml: Added requests as a dependency for downloading sample archives.

lavinigam-gcp and others added 4 commits June 1, 2025 12:18
This commit introduces the new `adk samples` command-line interface,
enabling users to easily discover, download, and prepare ADK example
agents for local use.

Key features in this initial version:

- Interactive Mode (`adk samples`):
  - Downloads official ADK samples from the GitHub repository to a local cache
    (default: `~/.adk/cache/samples/`, customizable with `--cache-path`).
  - Displays a table of available samples, including their names and extracted
    descriptions from their `agent.py` files.
  - Prompts the user to choose a sample by number.

- Direct Mode (`adk samples <sample_name>`):
  - Allows specifying a sample name directly for preparation.
  - Downloads samples to cache if not already present.

- Sample Preparation:
  - Copies the selected sample from the local cache to an `adk-samples`
    subdirectory in the user's target output path (default: current working
    directory, customizable with `--output-path`).
  - Prompts the user for their Gemini API key (securely).
  - Creates a `.env` file within the prepared sample's directory, pre-filled
    with the `GOOGLE_API_KEY` and configured for Google AI Studio backend.
  - Provides clear "Next steps" guidance on how to run the prepared sample
    using `adk web`, `adk run`, or `adk api_server`.

- Configuration:
  - Supports multiple sample sources via a configurable list (though V1
    defaults to the official adk-python repository).
  - Allows user-defined cache path (`--cache-path`) and output base path
    (`--output-path`).

File Changes:

- `src/google/adk/cli/cli_samples.py`: New file containing the core logic
  for downloading, caching, listing, copying samples, and .env creation.
- `src/google/adk/cli/cli_tools_click.py`: Modified to register the new
  `adk samples` command and its options (`--cache-path`, `--output-path`).
- `pyproject.toml`: Added `requests` as a dependency for downloading
  sample archives.
@wyf7107 wyf7107 requested a review from Jacksunwei June 2, 2025 16:35
@lavinigam-gcp
Copy link
Author

lavinigam-gcp commented Jun 2, 2025

Some comment for changes: (from: @wyf7107 )

— We can create .env in the parent folder — no need to create for each sample.
— We should not have two different folders — let's have everything as cache folder.
— If we have one folder — let's not call it cache folder → adk_sample_folder.
— By default: it should start adk web, unless user wants to explore other CLI option: adk cli or adk api_server
— Tests are missing for CLI.
— Current version only supports repo samples available at /contributing/samples. Need to integrate adk-samples repo in the next version.
— The description in many agents at /contributing/samples are not available and some are not correct. Need to add the correct names.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant